---
title: Создание контента в Markdown
description: Обзор синтаксиса Markdown, который поддерживается в Starlight.
---

Starlight поддерживает весь синтаксис [Markdown](https://daringfireball.net/projects/markdown/) в файлах с расширением `.md`, а также синтаксис [YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) для определения метаданных, таких как заголовок и описание.

Пожалуйста, обратитесь к [документации MDX](https://mdxjs.com/docs/what-is-mdx/#markdown) или [документации Markdoc](https://markdoc.dev/docs/syntax), если вы используете эти форматы файлов, поскольку поддержка и использование Markdown могут отличаться.

## Метаданные

Вы можете настроить отдельные страницы в Starlight, установив значения в их заглавной части.
Метаданные устанавливаются в верхней части ваших файлов между разделителями `---`:

```md title="src/content/docs/example.md"
---
title: Заголовок страницы
---

Содержимое страницы следует за вторым `---`.
```

Каждая страница должна включать хотя бы заголовок.
См. [справочник по метаданным](/ru/reference/frontmatter/) для получения информации обо всех доступных полях и о том, как добавлять настраиваемые поля.

## Встроенные стили

Текст может быть **жирным**, _курсивом_ или ~~зачёркнутым~~.

```md
Текст может быть **жирным**, _курсивом_ или ~~зачёркнутым~~.
```

Вы можете [ссылаться на другую страницу](/ru/getting-started/).

```md
Вы можете [ссылаться на другую страницу](/ru/getting-started/).
```

Вы можете выделить `код` обратными кавычками.

```md
Вы можете выделить `код` обратными кавычками.
```

## Изображения

Изображения в Starlight используют [встроенную оптимизацию ресурсов Astro](https://docs.astro.build/ru/guides/images/).

Markdown и MDX поддерживают синтаксис Markdown для отображения изображений, который включает альтернативный текст для экранных читателей и вспомогательных технологий.

![Иллюстрация планет и звёзд с надписью "astro"](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png)

```md
![Иллюстрация планет и звёзд с надписью "astro"](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png)
```

Относительные пути к изображениям также поддерживаются для изображений, хранящихся локально в вашем проекте.

```md
// src/content/docs/page-1.md

![Ракета в космосе](../../assets/images/rocket.svg)
```

## Заголовки

Вы можете структурировать контент, используя заголовки. Заголовки в Markdown обозначаются количеством символов `#` в начале строки.

### Как структурировать контент страницы

Starlight настроен так, чтобы автоматически использовать заголовок вашей страницы в качестве заголовка верхнего уровня и включать заголовок «Обзор» в начале оглавления каждой страницы. Мы рекомендуем начинать каждую страницу с обычного текстового содержания абзаца и использовать заголовки на странице от `<h2>` и ниже:

```md
---
title: Руководство по Markdown
description: Как использовать Markdown в Starlight
---

Эта страница описывает, как использовать Markdown в Starlight.

## Форматирование текста

## Заголовки
```

### Автоматические якорные ссылки для заголовков

Использование заголовков в Markdown автоматически создает якорные ссылки, позволяя вам ссылаться на определённые разделы вашей страницы:

```md
---
title: Моя страница с контентом
description: Как использовать встроенные в Starlight якорные ссылки.
---

## Введение

Я могу создать ссылку на [заключение](#заключение) ниже на этой же странице.

## Заключение

`https://my-site.com/page1/#введение` переходит непосредственно к моему Введению.
```

Заголовки уровня 2 (`<h2>`) и уровня 3 (`<h3>`) автоматически появятся в оглавлении страницы.

Узнайте больше о том, как Astro обрабатывает идентификаторы заголовков, в [документации Astro](https://docs.astro.build/ru/guides/markdown-content/#%D0%B8%D0%B4%D0%B5%D0%BD%D1%82%D0%B8%D1%84%D0%B8%D0%BA%D0%B0%D1%82%D0%BE%D1%80%D1%8B-%D0%B7%D0%B0%D0%B3%D0%BE%D0%BB%D0%BE%D0%B2%D0%BA%D0%BE%D0%B2)

## Вставки

Вставки полезны для отображения дополнительной информации рядом с основным контентом страницы.

Starlight предоставляет специальный синтаксис Markdown для отображения вставок. Вставки должны быть обернуты парой тройных двоеточий `:::` и могут иметь тип `note`, `tip`, `caution` или `danger`.

Вы можете указывать любые типы контента Markdown внутри вставок, но вставки лучше всего подходят для коротких и лаконичных блоков информации.

### Вставка «Заметка»

:::note
Starlight — это инструмент для создания сайтов с документацией, построенный с использованием [Astro](https://astro.build/ru/). Вы можете начать с этой команды:

```sh
npm create astro@latest -- --template starlight
```

:::

````md
:::note
Starlight — это инструмент для создания сайтов с документацией, построенный с использованием [Astro](https://astro.build/ru/). Вы можете начать с этой команды:

```sh
npm create astro@latest -- --template starlight
```

:::
````

### Настраиваемые заголовки вставок

Вы можете указать свой заголовок вставки в квадратных скобках после типа вставки, например, `:::tip[Небольшой совет]`.

:::tip[Небольшой совет]
Astro позволяет создавать быстрые сайты с помощью [архитектуры островков](https://docs.astro.build/ru/concepts/islands/)
:::

```md
:::tip[Небольшой совет]
Astro позволяет создавать быстрые сайты с помощью [архитектуры островков](https://docs.astro.build/ru/concepts/islands/)
:::
```

### Пользовательские иконки вставок

Вы можете указать пользовательскую иконку для вставки в фигурных скобках после типа панели или [пользовательского заголовка](#настраиваемые-заголовки-вставок), например, `:::tip{icon="heart"}` или `:::tip[Знаете ли вы?]{icon="heart"}` соответственно.
В качестве имени должна использоваться одна из [встроенных иконок Starlight](/ru/reference/icons/#все-иконки).

:::tip{icon="heart"}
Astro помогает создавать более быстрые веб-сайты с помощью [архитектуры островков](https://docs.astro.build/ru/concepts/islands/).
:::

```md
:::tip{icon="heart"}
Astro помогает создавать более быстрые веб-сайты с помощью [архитектуры островков](https://docs.astro.build/ru/concepts/islands/).
:::
```

### Другие типы вставок

Вставки с типами «caution» и «danger» полезны для привлечения внимания пользователя к деталям, которые могут сбивать с толку.
Если вы часто используете их, это может быть признаком того, что может быть нужно пересмотреть то, что вы документируете.

:::caution
Если вы не уверены, что хотите отличный сайт с документацией, подумайте дважды, прежде чем использовать [Starlight](/ru/).
:::

:::danger
Ваши пользователи могут быть более продуктивными и находить ваш продукт более простым в использовании благодаря полезным функциям Starlight.

- Чёткая навигация
- Цветовая тема, настраиваемая пользователем
- [Поддержка i18n](/ru/guides/i18n/)

:::

```md
:::caution
Если вы не уверены, что хотите отличный сайт с документацией, подумайте дважды, прежде чем использовать [Starlight](/ru/).
:::

:::danger
Ваши пользователи могут быть более продуктивными и находить ваш продукт более простым в использовании благодаря полезным функциям Starlight.

- Чёткая навигация
- Цветовая тема, настраиваемая пользователем
- [Поддержка i18n](/ru/guides/i18n/)

:::
```

## Цитаты

> Это цитата, которую обычно используют при цитировании другого человека или документа.
>
> Цитаты обозначаются символом `>` в начале каждой строки.

```md
> Это цитата, которую обычно используют при цитировании другого человека или документа.
>
> Цитаты обозначаются символом `>` в начале каждой строки.
```

## Блоки кода

Блок кода обозначается блоком с тремя обратными апострофами <code>```</code> в начале и в конце. Вы можете указать язык программирования после открывающих апострофов.

```js
// Javascript код с подсветкой синтаксиса.
var fun = function lang(l) {
	dateformat.i18n = require('./lang/' + l);
	return true;
};
```

````md
```js
// Javascript код с подсветкой синтаксиса.
var fun = function lang(l) {
	dateformat.i18n = require('./lang/' + l);
	return true;
};
```
````

### Возможности Expressive Code

Starlight использует [Expressive Code](https://expressive-code.com/) для расширения возможностей форматирования блоков кода.
Текстовые маркеры и плагины оконных рамок Expressive Code включены по умолчанию.
Рендеринг блоков кода можно настроить с помощью [параметра конфигурации `expressiveCode`](/ru/reference/configuration/#expressivecode) Starlight.

#### Текстовые маркеры

Вы можете выделить определённые строки или части блоков кода с помощью [текстовых маркеров Expressive Code](https://expressive-code.com/key-features/text-markers/) в первой строке вашего блока кода.
Используйте фигурные скобки (`{ }`), чтобы выделить целые строки, и кавычки, чтобы выделить строки текста.

Существует три стиля выделения: нейтральный для привлечения внимания к коду, зелёный для обозначения вставленного кода и красный для обозначения удалённого кода.
И текст, и целые строки можно пометить с помощью маркера по умолчанию или в сочетании с `ins=` и `del=` для получения желаемого выделения.

Expressive Code предоставляет несколько вариантов настройки внешнего вида примеров кода.
Многие из них можно комбинировать для получения наглядных примеров кода.
Ознакомьтесь с [документацией Expressive Code](https://expressive-code.com/key-features/text-markers/#configuration), чтобы узнать о расширенных возможностях. доступный.
Некоторые из наиболее распространённых примеров показаны ниже:

- [Пометка целых строк и диапазонов строк с помощью маркера `{ }`](https://expressive-code.com/key-features/text-markers/#marking-full-lines--line-ranges):

  ```js {2-3}
  function demo() {
  	// Эта строка (#2) и следующая выделены
  	return 'Это строка №3 этого фрагмента';
  }
  ```

  <Tabs syncKey="content-type">

  <TabItem label="Markdown/MDX">

  ````md
  ```js {2-3}
  function demo() {
  	// Эта строка (#2) и следующая выделены
  	return 'Это строка №3 этого фрагмента';
  }
  ```
  ````

  </TabItem>

  <TabItem label="Markdoc">

  ````markdoc
  ```js {% meta="{2-3}" %}
  function demo() {
    // Эта строка (#2) и следующая выделены
    return 'Это строка №3 этого фрагмента';
  }
  ```
  ````

  </TabItem>

  </Tabs>

- [Пометка выделенного текста с помощью маркера `" "` или регулярных выражений](https://expressive-code.com/key-features/text-markers/#marking-individual-text-inside-lines):

  ```js "Отдельные термины" /даже.*выражения/
  // Отдельные термины также могут быть выделены
  function demo() {
  	return 'Поддерживаются даже регулярные выражения';
  }
  ```

  <Tabs syncKey="content-type">

  <TabItem label="Markdown/MDX">

  ````md
  ```js "Отдельные термины" /даже.*выражения/
  // Отдельные термины также могут быть выделены
  function demo() {
  	return 'Поддерживаются даже регулярные выражения';
  }
  ```
  ````

  </TabItem>

  <TabItem label="Markdoc">

  ````markdoc
  ```js {% meta="'Отдельные термины' /даже.*выражения/" %}
  // Отдельные термины также могут быть выделены
  function demo() {
    return 'Поддерживаются даже регулярные выражения';
  }
  ```
  ````

  </TabItem>

  </Tabs>

- [Пометка текста или строк как вставленных или удалённых с помощью `ins` или `del`](https://expressive-code.com/key-features/text-markers/#selecting-inline-marker-types-mark-ins-del):

  ```js "return true;" ins="вставленные" del="удалённые"
  function demo() {
  	console.log('Это вставленные и удалённые типы маркеров');
  	// Оператор return использует тип маркера по умолчанию
  	return true;
  }
  ```

  <Tabs syncKey="content-type">

  <TabItem label="Markdown/MDX">

  ````md
  ```js "return true;" ins="вставленные" del="удалённые"
  function demo() {
  	console.log('Это вставленные и удалённые типы маркеров');
  	// Оператор return использует тип маркера по умолчанию
  	return true;
  }
  ```
  ````

  </TabItem>

  <TabItem label="Markdoc">

  ````markdoc
  ```js {% meta="'return true;' ins='вставленные' del='удалённые'" %}
  function demo() {
    console.log('Это вставленные и удалённые типы маркеров');
    // Оператор return использует тип маркера по умолчанию
    return true;
  }
  ```
  ````

  </TabItem>

  </Tabs>

- [Объединение подсветки синтаксиса с синтаксисом типа `diff`](https://expressive-code.com/key-features/text-markers/#combining-syntax-highlighting-with-diff-like-syntax):

  ```diff lang="js"
    function thisIsJavaScript() {
      // Весь этот блок выделяется как JavaScript,
      // и мы можем добавить к нему маркеры различий!
  -   console.log('Старый код, который нужно удалить')
  +   console.log('Новый и блестящий код!')
    }
  ```

  <Tabs syncKey="content-type">

  <TabItem label="Markdown/MDX">

  ````md
  ```diff lang="js"
    function thisIsJavaScript() {
      // Весь этот блок выделяется как JavaScript,
      // и мы можем добавить к нему маркеры различий!
  -   console.log('Устаревший код, который нужно удалить')
  +   console.log('Обновлённый и крутой код!')
    }
  ```
  ````

  </TabItem>

  <TabItem label="Markdoc">

  ````markdoc
  ```diff {% meta="lang='js'" %}
    function thisIsJavaScript() {
      // Весь этот блок выделяется как JavaScript,
      // и мы можем добавить к нему маркеры различий!
  -   console.log('Устаревший код, который нужно удалить')
  +   console.log('Обновлённый и крутой код!')
    }
  ```
  ````

  </TabItem>

  </Tabs>

#### Рамки и заголовки

Блоки кода могут отображаться внутри оконного фрейма.
Рамка, похожая на окно терминала, будет использоваться для языков сценариев оболочки (например, `bash` или `sh`).
Другие языки отображаются внутри рамки в стиле редактора кода, если они включают заголовок.

Необязательный заголовок блока кода может быть установлен либо с помощью атрибута `title="..."` после открывающих обратных кавычек блока кода и идентификатора языка, либо с помощью комментария к имени файла в первых строках кода.

- [Добавление вкладки имени файла с помощью комментария](https://expressive-code.com/key-features/frames/#code-editor-frames)

  ```js
  // my-test-file.js
  console.log('Привет, мир!');
  ```

  <Tabs syncKey="content-type">

  <TabItem label="Markdown/MDX">

  ````md
  ```js
  // my-test-file.js
  console.log('Привет, мир!');
  ```
  ````

  </TabItem>

  <TabItem label="Markdoc">

  ````md
  ```js
  // my-test-file.js
  console.log('Привет, мир!');
  ```
  ````

  </TabItem>

  </Tabs>

- [Добавление заголовка в окне терминала](https://expressive-code.com/key-features/frames/#terminal-frames)

  ```bash title="Установка зависимостей…"
  npm install
  ```

  <Tabs syncKey="content-type">

  <TabItem label="Markdown/MDX">

  ````md
  ```bash title="Установка зависимостей…"
  npm install
  ```
  ````

  </TabItem>

  <TabItem label="Markdoc">

  ````markdoc
  ```bash {% title="Установка зависимостей…" %}
  npm install
  ```
  ````

  </TabItem>

  </Tabs>

- [Отключение оконных рамок с помощью `frame="none"`](https://expressive-code.com/key-features/frames/#overriding-frame-types)

  ```bash frame="none"
  echo "Это не отображается как терминал, несмотря на использование языка bash"
  ```

  <Tabs syncKey="content-type">

  <TabItem label="Markdown/MDX">

  ````md
  ```bash frame="none"
  echo "Это не отображается как терминал, несмотря на использование языка bash"
  ```
  ````

  </TabItem>

  <TabItem label="Markdoc">

  ````markdoc
  ```bash {% frame="none" %}
  echo "Это не отображается как терминал, несмотря на использование языка bash"
  ```
  ````

  </TabItem>

  </Tabs>

## Спойлеры

Спойлеры (также известные как «раскрытия» или «аккордеоны») полезны для того, чтобы скрыть содержимое, которое не имеет непосредственного отношения к делу.
Пользователи могут нажать на краткое содержание, чтобы развернуть его и просмотреть полный текст.

Используйте стандартные элементы HTML [`<details>`](https://developer.mozilla.org/ru/docs/Web/HTML/Element/details) и [`<summary>`](https://developer.mozilla.org/ru/docs/Web/HTML/Element/summary) в вашем Markdown-контенте, чтобы создать виджет раскрытия информации.

Внутри элемента `<details>` можно использовать любой другой синтаксис Markdown.

<details>
<summary>Где и когда созвездие Андромеды видно лучше всего?</summary>

[Созвездие Андромеды](<https://ru.wikipedia.org/wiki/%D0%90%D0%BD%D0%B4%D1%80%D0%BE%D0%BC%D0%B5%D0%B4%D0%B0_(%D1%81%D0%BE%D0%B7%D0%B2%D0%B5%D0%B7%D0%B4%D0%B8%D0%B5)>) наиболее заметно на ночном небе в ноябре на широтах от `+90°` до `-40°`.

</details>

```md
<details>
<summary>Где и когда созвездие Андромеды видно лучше всего?</summary>

[Созвездие Андромеды](<https://ru.wikipedia.org/wiki/%D0%90%D0%BD%D0%B4%D1%80%D0%BE%D0%BC%D0%B5%D0%B4%D0%B0_(%D1%81%D0%BE%D0%B7%D0%B2%D0%B5%D0%B7%D0%B4%D0%B8%D0%B5)>) наиболее заметно на ночном небе в ноябре на широтах от `+90°` до `-40°`.

</details>
```

## Другие возможности Markdown

Starlight поддерживает все синтаксические возможности Markdown, такие как списки и таблицы. Посмотрите [шпаргалку по Markdown от The Markdown Guide](https://www.markdownguide.org/cheat-sheet/) для изучения всех возможностей синтаксиса Markdown.

## Расширенная конфигурация Markdown и MDX

Starlight использует Markdown и рендерер MDX от Astro, основанный на `remark` и `rehype`. Вы можете добавить поддержку пользовательского синтаксиса и поведения, добавив `remarkPlugins` или `rehypePlugins` в свой файл конфигурации Astro. Дополнительную информацию см. в статье [Плагины Markdown](https://docs.astro.build/ru/guides/markdown-content/#%D0%BF%D0%BB%D0%B0%D0%B3%D0%B8%D0%BD%D1%8B-markdown) в документации Astro.

## Markdoc

Starlight поддерживает создание контента в Markdoc с помощью экспериментальной [интеграции с Astro](https://docs.astro.build/ru/guides/integrations-guide/markdoc/) и пресета Starlight Markdoc.

### Создание нового проекта с Markdoc

Начните новый проект Starlight с предварительно настроенным Markdoc с помощью команды `create astro`:

import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';

<Tabs syncKey="pkg">
<TabItem label="npm">

```sh
npm create astro@latest -- --template starlight/markdoc
```

</TabItem>
<TabItem label="pnpm">

```sh
pnpm create astro --template starlight/markdoc
```

</TabItem>
<TabItem label="Yarn">

```sh
yarn create astro --template starlight/markdoc
```

</TabItem>
</Tabs>

### Добавление Markdoc в существующий проект

Если у вас уже есть сайт Starlight и вы хотите добавить Markdoc, выполните следующие действия.

<Steps>

1.  Добавьте интеграцию Markdoc:

    <Tabs syncKey="pkg">

    <TabItem label="npm">

    ```sh
    npx astro add markdoc
    ```

    </TabItem>

    <TabItem label="pnpm">

    ```sh
    pnpm astro add markdoc
    ```

    </TabItem>

    <TabItem label="Yarn">

    ```sh
    yarn astro add markdoc
    ```

    </TabItem>

    </Tabs>

2.  Установите пресет Markdoc для Starlight:

    <Tabs syncKey="pkg">

    <TabItem label="npm">

    ```sh
    npm install @astrojs/starlight-markdoc
    ```

    </TabItem>

    <TabItem label="pnpm">

    ```sh
    pnpm add @astrojs/starlight-markdoc
    ```

    </TabItem>

    <TabItem label="Yarn">

    ```sh
    yarn add @astrojs/starlight-markdoc
    ```

    </TabItem>

    </Tabs>

3.  Создайте файл конфигурации Markdoc по адресу `markdoc.config.mjs` и используйте пресет Markdoc:

    ```js
    import { defineMarkdocConfig } from '@astrojs/markdoc/config';
    import starlightMarkdoc from '@astrojs/starlight-markdoc';

    export default defineMarkdocConfig({
    	extends: [starlightMarkdoc()],
    });
    ```

</Steps>

Чтобы узнать больше о синтаксисе и возможностях Markdoc, смотрите [документацию](https://markdoc.dev/docs/syntax) или [Руководство по интеграции Markdoc в Astro](https://docs.astro.build/ru/guides/integrations-guide/markdoc/).

### Настройка пресета Markdoc

Пресет `starlightMarkdoc()` принимает следующие параметры конфигурации:

#### `headingLinks`

**тип:** `boolean`  
**по умолчанию:** `true`

Определяет, будут ли заголовки отображаться с кликабельной ссылкой-якорем.
Эквивалентно опции [`markdown.headingLinks`](/ru/reference/configuration/#markdown), которая применяется к файлам Markdown и MDX.

```js "headingLinks: false"
export default defineMarkdocConfig({
	// Отключение поддержки ссылок-якорей для заголовков по умолчанию
	extends: [starlightMarkdoc({ headingLinks: false })],
});
```
